#!/usr/bin/python
# -*- coding: utf-8 -*-

#This file is part of pyLot library.
#
# pyLot is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# pyLot is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with pyLot.  If not, see <http://www.gnu.org/licenses/>.

__author__ = u'Pierre Puiseux, Guillaume Baty'
__copyright__ = u"Copyright 2011-2012 (C) andheo, Université de Pau et des Pays de l'Adour"
__credits__ = [u'Pierre Puiseux', u'Guillaume Baty']
__license__ = "GNU Lesser General Public License"

__all__ = [u'generate_rst_class_doc',
           u'SphinxDocGenConf']

from pyLot.core import ENCODING
import inspect

class SphinxDocGenConf (object):
  u"""
  A configuration class for generate_rst_class_doc function.
  
  To create a new config, just create an instance of SphinxDocGenConf and fill
  the following fields :
  
    - short_desc (unicode) : short description
    - long_desc (unicode) : long description
    - authors (list of unicode) : authors
    - summary_adds (unicode) : text you want to add to summary
    - ref_adds (unicode) : text you want to add to reference part
    - force_refs (list of unicode) : method you want to reference even if 
      they are private or have no documentation.
  """
  def __init__(self):
    self.short_desc = u''
    self.long_desc = u''
    self.authors = []
    self.summary_adds = u''
    self.ref_adds = u''
    self.force_refs = []

def generate_rst_class_doc (class_path, config=SphinxDocGenConf()):

  module_path = '.'.join(class_path.split('.')[:-1])
  class_name = class_path.split('.')[-1]

  try :
    mod = getattr(__import__(module_path), module_path.split('.')[-1])
    Class = getattr(mod, class_name)
  except (ImportError, AttributeError) :
    mod = __import__(module_path, fromlist=[module_path])
    Class = getattr(mod, class_name)

  dict_property = {}
  dict_public = {}
  dict_private = {}

  try :
    parent_class = Class.__base__
  except AttributeError :
    parent_attrs = []
  else :
    parent_attrs = dir(parent_class)

  for attr_id in dir(Class) :
    if attr_id.startswith('_') and attr_id not in config.force_refs:
      pass
    else :
      attr = getattr(Class, attr_id)
      if attr_id in config.force_refs :
        if attr_id.startswith('_') :
          dict_private[attr_id.decode(ENCODING)] = attr
        elif inspect.isdatadescriptor(attr):
          dict_property[attr_id.decode(ENCODING)] = attr
        else :
          dict_public[attr_id.decode(ENCODING)] = attr
      else :
        if inspect.isdatadescriptor(attr):
          dict_property[attr_id.decode(ENCODING)] = attr
        elif attr_id not in parent_attrs and attr.__doc__ :
          dict_public[attr_id.decode(ENCODING)] = attr

  class_path = class_path.decode(ENCODING)
  class_name = class_name.decode(ENCODING)
  module_path = module_path.decode(ENCODING)

  output_text = u''


#.. hlist::
#  :columns: 4
  output_text += u"""
%(CLASS_NAME_UNDERLINE)s
**%(CLASS_NAME)s** Class Reference
%(CLASS_NAME_UNDERLINE)s

.. testsetup::

  from %(MODULE_PATH)s import %(CLASS_NAME)s

.. autoclass:: %(CLASS_PATH)s
  :show-inheritance:
  :members:

""" % dict(
           CLASS_NAME=class_name,
           CLASS_NAME_UNDERLINE=u'=' * (len(class_name) + 20),
           CLASS_PATH=class_path,
           SHORT_DESC=config.short_desc,
           MODULE_PATH=module_path,
           )

  return output_text

if __name__ == '__main__' :

  CLASS_PATH = u'pylot.qtgui.GuiMainManager'
  AUTHORS = [
    u'Guillaume Baty <guillaume.baty@andheo.fr>',
    u'Pierre Puiseux <pierre.puiseux@univ-pau.fr>'
  ]
  SHORT_DESC = u'The Class class provides ...'
  LONG_DESC = u'long desc'

  CONFIG = SphinxDocGenConf()
  CONFIG.short_desc = SHORT_DESC
  CONFIG.long_desc = LONG_DESC
  CONFIG.authors = AUTHORS

  print generate_rst_class_doc(CLASS_PATH, CONFIG)
